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The S708 software supports the use of an IMS BOOS board in an IBM PC AT or 
IBM PC XT. 

The software includes the module motherboard software which can be used to 
set the programmable switches on the IMS BOOS motherboard. These switches 
determine the topoJogy of the transputers hosted on the motherboard. The mod- 
ule motherboard software also contains a rietwork mapper (worm) program which 
is used to explore the inter-connections of these transputers and provide a means 
of checking the topology. 

A DOS device driver is provided to interface the IMS BOOS to the DOS operating 
system. 

Programs are run on the BOOS by using the server program provided. The server 
loads programs to transputer networks and provides file and terminal services to 
the executing program. Both the module motherboard software and the WORM 
are executed in this way. 
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1 How to use the guide 



The S708 User Guide is broadly structured into four sections; 

• Introduction 

• User Guide 

• Reference manual 
« Appendices 

1.1 Introduction 

This section gives an overview of the components of the S708 product and its 
operating requirements. 

1.2 User guide 

This section provides information on how to use tlie components of the product 



1.3 Reference manual 

Tlie reference manual gives the detailed technical information that was not ap- 
propriate to the user guide. 



1.4 Appendices 

The appendices are provided for rapid reference. 
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2 Introduction 



This document relates to the S708 device driver product for an IBM PC running 
MS-DOS. The S708 is a software package consisting of a WSDOS device driver 
and a set of tools tor use with the IMS BOOB board product. The device driver, 
once installed, provides a mechanism for loading transputers via a server. 



2.1 Product components 

The S708 is supplied in two formats: 5j" 360K and 3|" 720K MS-DOS floppy 
disks. The contents of the disk should be as follows: 

• Device driver, 

• INMOS server. 

• Module Motherboard Software (MMS), 



2.2 Operating requirements 

The S708 device driver is intended for use with IBM PC and compatible machines 
running MSDOS V2.10 or greater. 
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3 Installation 



3.1 Introduction 

This section describes how 1o install the S708 Software on an IBM-PC Compat- 
ible, 



3.2 Hardware Installation 

Before it is possible to successfully install the device driver it is necessary that 
the BOOa card is installed, in accordance with the B008 User Reference Guide 
which is supplied with the board hardware. Whilst installing the board, take note 
of the following configuration information which will be required in order to install 
the device driver properly: 

• Base 10 Address of the BOOS Card 

• DMA Channel Number (B008-0a and B008-0b only) 

3.2.1 Copying the Files 

First move to the target disk drive and make a suitable directory using the DOS 
mkdir command. This directory can be anywhere on the disk. 

Having made the directory, move in to it using the DOS cd command, insert the 
S708 distribution disk in drive A: and issue the following command line: 

xcopy a:\* .* /s 

If you have an earlier version of MS-DOS or PC-DOS which doesn't support the 
xcopy command, tssue the following commands instead: 

copy a;\*.* 

mkdir iserver 

copy a:iserver\*.* iserver 



The exact contents of the release disk are given in an appendix. The contents 
of the directory after extraction will be as folfows: 
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BOOS MMS Hardwire file for the BOOS 

ISERVER.EXE Executable copy of the iserver 

ISERVER ..... Directory containing the sources for the isen/er 

MMS2 .B4 The module motherboard software 

PCMMS , ITM Iterm file for the MMS on a PC 

S708DRIV.SYS The DOS Device Driver 

SOFTWIRE Example softwire configuration 

3.2.2 Reconfiguring DOS to accept the driver 

Having physically installed both the hardware and the software components in 
the PC it is necessary to tail DOS to recognise the new device, This is done 
by altering a file called CONFIG.SYS in the root directory of the boot disk by 
adding a line describing the device driver. 

The syntax of the CONFIG.SYS line for the BOOS Driver is: 

DE\/\CE^pathname [/A address] [ID chan \ N] [/N name] [/I inLnum] 

where: pathname is the full DOS pathname of the device driver file. 

The pathname parameter is the pathname of the S708DRIV.SYS file on 
the disk as installed in the previous step. 

address is the 10 address of the BOOS card, as set by the hardware 
switches on installation. 

Chan is the DMA channel number (0, 1 , or 3). On older BOOSs tinis 
nunnber must also be set on the board itself using switches. For details 
see the manual supplied with your BOOS. 

If the character 'N' is specified instead of a decimal digit then the driver 
will not attempt to use the DMA facilities of the 8008. If DMA usage by 
the 8008 has been disabled on the card switches then this parameter 
mustbB set to 'N'. 

name is the DOS device name which the device will assume. Use this 
option with care if you intend to use inmos software products which may 
expect this name to be the default name 'LINKI'. The name cannot be 
more than the DOS limit of eight characters. 

inLnum is the interrupt request line used by the BOOS, which should be set 
to the correct value for your board. For details see the manual supplied 
with your B008. The default is Irq3. On older BOOSs the number must 
also be set up on the board itself. 
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3.2 Hardware Installation 



The following are examples of typical CONFIG.SYS lines for the device driver: 

DEVICE = C:\S708\S708DRIV.SYS /A 150 /NAME IMSB008 /D N 
DEVICE = C:\S708\S708DRIV.SYS /A 200 /D 1 

Having altered the config.sys file, reboot the machine and run tlie MMS as de- 
scribed in the relevant section of this document to confirm the correct installation 
of the device and software. 
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4 Module motherboard 
software 



4.1 Introduction 

The range of INMOS Module IVIotherboards[1] and Modules[2) allow many differ- 
ent configurations of modules and the connections between them to be specified 
without making physical changes to the boards. The configuration is performed 
by sending configuration data to the IMS C004 link switches[3] on the board. The 
MMS (Module Motherboard Software) is designed to make it easy to generate 
the data needed to configure a system of motherboards. 

The MMS provides interactive control of a motherboard or a system of moth- 
erboards. It presents a menu-driven interface allowing the user to set up the 
motherboards and also to create configuratior^ programs for use outside of the 
MMS. 

This chapter describes how to use the hardware and software description lan- 
guages needed to describe the hardware system and the desired connections 
within that system, together with a description of the MMS program itself. 

The MMS uses a terminal description file called pcmms . ITM. In order for the 
MMS to access this file it is necessary to set up an environment variable caiied 
ITERM. This can be done by including the following line in your autoexec, bat 
file: 

set ITERM==PCMMS.ITM 



4.2 Getting started 

in the rest of this manual it is assumed that the motherboards in use have been 
set up, and that you are familiar with the user guides for them. 

In order to be able to configure the links connecting the IMS C004s on the moth- 
erboards the MMS reads files, known as the 'softwire' and 'hardwire' fiEes. The 
first of these contains a description of the connections that the user wants to 
make using the programmable link connections. The second contains a descrip- 
tion of the hardware configuration of the boards being used. 

The hardwire file is needed so that the MMS is able to determine what con- 
nections [t is possible to make; it contains information on such things as the 
number of IMS C004s, number of module slots, and the connections between 
them. Once this descriptJon has been set up no changes will have to be made 
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12 4 Module motherboard software 

unless physical changes are made to the motherboard system. If you are using 
a single IMS 6008 or IMS B01 4 there should not be any need to understand the 
information in the hardwire file in great detail as Ihe supplied hardwire description 
ftles for these boards can be used without modification. 

The softwire file is needed to specify both the connections from module to module 
and from module to edge on a motherboard. Unlike the hardwire file the softwire 
fUe will be tailored for the application being run. 

You should read section 4.4 on describing softwire connections and study the 
example files supplied with the MMS before attempting to run the MMS or trying 
to set up your own softwire description. To get going initially 11 is probably be 
easiest to modify a copy of one of the example filesets provided. 



4.3 Using the MMS 

4.3.1 Running the MMS 

To run the MMS, move to the directory in which the contents of the distribution 
disk were unpacked and type 

i server /sb mms2,b4 softwire hardwire 

replacing' softwire and hardwire by files containing the softwire description and 
hardwire description respectively. The MMS will display a menu screen and 
pronnpt key command. At this point the user can enter any of the command 
codes listed on the menu| including h for heip and q for quit. 
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4,3 Using the MMS 13 

4.3.2 Menu options 

The menu options avaitable are as follows: 

H — Help 

Q — Quit 

S — Set C004 links 

C — Check source files 

T — Toggle diagnostics 

N — Network mapper 

M — Manual command entry 

L — Change link numbers 

V — View source files 

R — Reset subsystem 

} — Initialise C004s 

B — Create a bootable file 

O — Create an occam table 

The menu options are described below. 

Help 

The help option allows the user to call up a help screen for each of the menu 
opttons. The help screen for the help option displays some Information about 
the MMS, including Implementation limits of number of IMS C004s, IMS T212s, 
slots, etc. The MMS version number is also displayed. 

Quit 

Return to operating system. 

Set C004 links 

The set command performs the IMS C004 setting as specified in the softwire 
source file. 

To carry out this command the MMS first reads the hardwire description, and 
builds up an internal representation of the motherboards. The MMS then at- 
tempts to boot the configuration pipeline with a special worm which allows com- 
mands to be sent to the IMS C004s. The MMS then reads the softwire file, and 
generates and sends the configuration commands to the configuration pipeline. 

If errors are detected at any stage, they are reported and the command aban- 
doned. 
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14 4^ Module motherboard software 

Check source files 

The check source files command is essentiaJly the same as the set command 
except that no attempt is made to perform the actual configuralion of the boards. 
[n this way it is possible to check a set of source files without having the corre- 
sponding hardware on-line. 

Toggle diagnostics 

Tills toggles the diagnostic mode- In this mode any command sequences that 
are generated are also displayed on the screen. 

Network mapper 

The network mapper command sends a worm into the transputer network using 
the currently set pipe-in link. The mapper is currently able to detect IMS T212s, 
IMS T414S. IMS T800S and IMS M212s, although 6K bytes of memory is re- 
quired, and therefore it will not be able to find the IMS T212s in the configuration 
pipeline as they have no external memory. 

Manual command entry 

The manual command option allows the user to send IMS C004 command se- 
quences to any IMS C004 specified in the hardwire file. These sequences are 
of the same form as those generated automatically: 

• IMS C004 id 

• IMS C004 command 

• any parameters required by the command 

It is not possible to send the enquire command (BYTE 2) as no facility is provided 
for returning information from the configuration pipeline. 

Change link numbers 

The link change options aflows the user to change the links which the MMS 
uses to communicate with the configuration pipeline and the module pipeline. 
The default settings are: 

Link 1 - configuration pipeline 
Link 2 - module pipeline 

It is not possible to specify the same link for both pipelines. 
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4.3 Using tha MMS 15 

View source file 

The view option allows the user to view the source of the softwire and hardwire 
files. It prompts lor which file to view and which line number within that file to 
view. That line together with the preceding and following two are then displayed. 

Reset subsystem 

The reset option asserts the subsystem reset on the host transputer, causing 
the system of mothert>oards to be reset. This will not cause She IMS C004 
configuration to be lost. 

Initialise C004s 

The initialise option causes a software reset to be sent to each IMS C004 in the 
motherboard system. In order to do this the hardwire file is read to determine 
the number and whereabouts of each of the IMS C004s within the system. 

Create a bootable file 

The bootable file option is simiiar to the set option except that the configuration 
commands generated are written to a file containing a program which will con- 
figure the network when it is booted from the server. The generated program 
expects the configuration pipeline to be connected to the root transputer via the 
configuration pipeline link set when the program is generated. This configura- 
tion program can be used without the MMS being present on the system. When 
run, the program will either print a message stating that the configuration was 
successful or unsuccessful. 

Create an occam table 

The Occam table option is similar to the set command except that the con- 
figuration commands generated are written to a file in the form of an occam 
table together with a program which controls the configuration pipeline during 
the network configuration. This OCCam table can be sent to the configuration 
pipeline using the extraordinary link communication procedures[4] to output the 
table. The table output will fail if the network configuration is not successful. 
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16 4 Module motherboard software 

For example the following piece of Occam can be used configure a network, as- 
suming that the labEe generated by the MMS is contained in the file table , inc: 

— A procedure to configure module motherboards 

— at run time with a table produced by the mms2 
^^ software . 

#INCLUDE "hosticinc" 

PROC config (CEAN OF SP fs, ts) 

#IKCLtJDE "linkaddr.inc" 

#lNCliUDE "table. inc" — occam table 

#USE "hostio.lib" 

#USE "xlink.lib" 

CHAN OF ANY from.t2, to,t2; 
PORT OF BYTE analyse, reset: 

PLACE tO,t2 AT linkl.out: 

PLACE from.t2 AT linkl-in: 

PLACE reset AT (0 >< (MOSTNEG INT)) » 2: 

PLACE analyse AT (4 X (MOSTNEG INT)) » 2: 

VAL ONEms IS 15: 
VAL fail, delay IS 8000: 

BOOL failed, f ailed2 : 
BYTE result : 
INT time: 
[4] BYTE num: 
TIMER timer : 

PROC Pause () 
SEQ 

timer ? time 

timer ? AFTER time PLUS (5 * ONEms) 
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SEQ 

analyse ! (BYTE) — Reset subsystem 

reset 1 (BYTE) 

Pause ( ) 

reset ! 1 (BYTE) 

Pause ( ) 

reset f (BYTE) 

Pause () 

timer ? time 

time := time PLUS fail. delay 

FAR 

OutputOrFail.t (to.t2. Table, timer, time, failed) 
InputOrFail.t (from.t2| num, timer/tiroe, failed2) 

IF 

failed 
SEQ 

Reinitialise (to. t2) — clean up after failure 
so.write-String.nl (fs, ts, 

"Unable to configure T2 chain.") 
TRUE 

VAL INT32 n RETYPES num: 

— print no. of T2s found. 
SEQ 

so. write. String (fs,ts,"Size of T2 chain: ") 
so. write. int32 (fs, ts, n + 1, 0) 
so. write, string.nl (fs, ts, ".") 



4.4 Describing the software configuration 

The following sections describe how to specify the soft connections required on 
a system of motherboards. 

The syntax of both the softwire and hardwire descriptions are described in a 
modified Backus-Naur Form (BNF). For example, 

edge Jo. edge, line = EDGE edge^idTO edge edgeJd 

This means 'An edge.to.edgeJine Is the keyword EDGE, followed by an edge.id, 
lollowed by the keywords TO edge, followed by an edge.id'. 
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16 4 Module motherboard software 



A vertical bar ( | ) means 'or", for example: 

softwife.line = slotto.slotJine 
I slot.to.edge.line 
I edge.to.edge.line 

The written structure of the description is specified by the syntax. Each statement 
normally occupies a single line, and the indentation of each statement fornis an 
intrinsic part of the syntax of the language. For example, 

board.softwiresJine = PIPE boardJd 

{ softwire.tine } 

This means 'A board.softwiresJine \s the keyword pipe followed by a bOBfd.id 
followed by zero or more softwire. lines, each on a separate line, and indented 
two spaces further than pipe'. Curly brackets { and } are used to indicate the 
number of times a syntactic object occurs. { object } means, 'zero or more 
objects, each on a separate line'. Similarly {i object } means, 'one or more 
objecis, each on a separate line.' [ object ] means that object \s optional. 

Comments are introduced by a double dash ( — ), and extend to the end of the 
line. 

Summaries of the syntax of the description languages are given in appendices 
C and D. 



4.4.1 Softwire definition 

The softwire connections alJow links on modules on a motherboard to be con- 
nected to other modules and edges, without requiring a direct hardwired route 
between the two. instead the MMS routes the channels via the IMS C004s on 
the motherboard. It may not be possible to make every possible connection 
desired. This depends on how the IMS C004s and module slots are physically 
connected to each other. 
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A SOFTWIRE description has the following basic structure: 

SOFTWIRE 
PIPE 



. soft connections for board 
PIPE 1 

. soft connections for board 1 



PIPE n 
, soft connections for board n 
END 

The syntax o* a softwire description is: 

softwire.deschption = SOFTWIRE 

{ boardsoftwires.line} 

END 

boardsoftwiresJine = pipe board Jd 

{ softwire.line} 

The softwire lines are specified in three ways: 

• Edge to edge connections 

• Slot to edge connections 

• Slot to slot connections 
The syntax for softwire lines is: 

softwire.line = edge, to, edge.line 
I slolto.edge.Une 
I slot.to.slot.line 
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An edge to edge connection simpty specifies that the two edges named are to 
be connected together. For example, 

EDGE 4 TO EDGE 7 

The syntax for an edge to edge line is: 

edgeJo.edge.line = edge edge.id to edge edge.id 

A slot to edge line specifies that the edge is to be connected to the specified 
link on the slot. For example, 

SLOT 3, LINK 3 TO EDGE 6 

The syntax for a slot to edge line is: 

sfotto.edgeJine = SLOT slotid, LINK link.num TO edge edge.id 

A slot to slot line specifies a connection is to be made between a link on one 
module to a link en another module, for example: 

SLOT 2, LINK TO SLOT 1, LINK 

specifies that link of slot 2 will be sottwired to link of slot 1 . 

The slot to slot line has another form which includes a VIA statement. This form 
specifies that the connection is to be made via the two edges specifed. This 
form is really just a shorthand equivalent to two slot to edge lines. For example 

SLOT 2r LINK TO SLOT 12, LINK 3 VIA EDGE 3, 6 
Is equivalent to the longer form: 

SLOT 2r LINK TO EDGE 3 
SLOT 12, LINK 3 TO EDGE € 

It is the user's responsibility to complete the connection by hardwiring the two 
edge connectors together. The purpose of this is to allow soft connections to 
be set up Indirectly via edge links where the boand architecture does not permit 
direct connection. 
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The syntax for slot to slot lines is: 

$loUo.$lot.line=S'LOT slotidf LINK link.num TO SLOT slotid, 
LINK link.num [via.sect'ion] 

via.section ^VIA edge edge.id, edge.id 

As an example of a complete file using these constmcts, the following softwires 
file specifies all the connections in the diagram below: 

SOFTWIRE 
PIPE 

SLOT 0, LINK 3 TO SLOT 1, LINK 3 

SLOT 0, LINK TO SLOT 1, LINK VIA EDGE 0, 1 

SLOT 2f LINK TO EDGE 2 
END 



SLOTO 





LINK CABLE 



4.5 Describing the hardware configuration 

Tliis section describes how to define the hardware configuration of a motherboard 
system. The MMS needs to know how the slots, llv!S C004s and edges are 
connected together on the board in order to be able to determine whether a 
particular set of softwlre connections is possible or not. 

The following sections will describe what is required In each section of a board 
definition, including some examples. 
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4.5.1 Hardwire definition 

A typical hardwire definition would look something like the following: 
. define boarda 

DEF boardb 

— sizes section 

— t2chain section 

— hardwires section 

PIPE boarda,. boardb, boardb, boarda, boarda END 

The definition consists of two separate parts 

• The definition of board types 

• The definition of the pipeline 

The pipeline definition tells the MMS how the boards in the system are arranged. 
In the example above we have the following system: 




boardb 




boarda 




boarda 







The board definition, on the other hand, specifies the connections within a par- 
ticular board type. Each section of the board definition wilJ now be described in 
more detail. 

The syntax for a hardwire description is: 

hardwire. description = {^ board.deflnition } 
pipeiine. description 



board.definition 



pipeline, description 



DEF board.name 
sizes 
t2.chain 
tiardwires 

PIPE { board.name } 
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Sizes sectton 

The sizes section is used to tell the MMS how many IMS T212s, IMS C004s, 
slots and edges are present on the board for example: 

SIZES 

T2 1 

C4 1 

SLOT 3 

EDGE 2 
END 

describes a board with one IMS T212, one IMS C004, three module slots, and 
two edge connections. 

The syntax of the sizes section is: 

sizes = SIZES 

T2 positive. integer 
C4 positive. integer 
SLOT positive. integer 
EDGE positive, integer 

END 
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T2 ctiain section 

The T2 chain section tells the MMS how the T2 chain is connected to the IMS 
C004S. It specifies which links of the IMS T212s are connected to the configu- 
ration links of the IMS C004s. For example, 

T2CHAIN 

T2 0, LINK C4 

T2 0, LINK 3 C4 1 

T2 1, LINK C4 2 

T2 1, LINK 3 C4 3 
END 

describes the following system: 





C4 


2 




C4 2 
























1 


T2 


1 


T2 1 


2 


















3 






3 








C4 1 




C4 3 







The syntax of the T2 chain section is: 

t2.chain = T2CHAIN 

{ t2.c4.iine} 
END 

t2.c4.line = T2 tZid, LINK chain.link.num C4 c4.id 

t2.id = positlve.integer 

chain, fink, num = 
I 3 

c4jd = 0..31 
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Hardwire section 

The hardwire section describes how the slots^ edges and IMS C004s are con- 
nected together. A typical stnjcture is as follows: 

HARDWIRE 

— pipeline 

— slots to IMS C004S 

— edges to IMS C004s 
slots to edges 

END 

The sections may appear in any order and lines Irom each may be freely inter- 
mixed, although organising it as above will aid understanding. 

The syntax of the hardwire section is: 



hardwires 



HARDWIRS 

{ hardwire. tir}e } 

END 



hardwire.line 



= stot.to.stot 

I c4.to.slot 

I c4.to.edge 

1 stotAo.edge 



The pipeline section describes how the module slots on the motherboard are 
connected together to form the module pipeline. In general, link 2 of a slot is 
connected to link 1 of the following slot so that it conforms with the module 
motherboard architecture(1]. It is not possible to separate the input and output 
channels of the links. For example, 

SLOT 0, LINK 2 TO SLOT 1, LINK 1 
SLOT 1, LINK 2 TO SLOT 2, LINK 1 
SLOT 2, LINK 2 TO SLOT 3, LINK 1 

describes the following four module pipeline 



SLOTO 



SL0T1 



SLOT 2 



SLOT 3 
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The syntax of slot to slot lines is: 

stot.to.slot = SLOT sloUd, LIHK link.num TO SL03! shtid, 
LINK link.num 



shtid 



= positive.integer 



The slots to IMS C004s section describes how the non-pipeline links of the sbts 
are connected to the IMS C004 link switches. In general both links and 3 will 
be taken to an IMS C004. It is possible to specify that the input and output 
channels of a link are taken to dtfferent IMS C004s by including an I or O in the 
definition. For example, 

C4 0, LINK TO SLOT 0, LINK 

C4 1, LINK 0, O TO SLOT 1, LINK 0, T 

C4 1, LINK 1, I TO SLOT 1, LINK 0, O 

C4 1, LINK 5, TO SLOT 2, LINK 3, I 

Specifies the following connections 





f\ 








o.o 


o 


* 


4 


5.0 






O** u 






U*t 1 






















J 


1.1 

O.O 










OJi 


r 








1 


SLOTO 


2 


1 


SL0T1 


2 


1 


SLOT 2 


2 


































t^T 





The syntax of IMS C004 to slot lines is: 

c4.to.slot = C4 c4.}d, LINK c4Jink.no [, i/o ] TO SLOT slot no, 
LINK link.num [, iyo] 

i/o = 1 

I o 

link,num = 

I 1 

I 2 

I 3 

c4Jfnk. no = positive.integer 
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The edges to IMS C004s section specifies which edges, if any, are connected to 
the IMS C004S on the board. As with slots to IMS C004s, the input and output 
channels can be handled separately. For example, 

C4 0, LINK 0, I TO EDGE 1, O 
C4 0, LINK 4 TO EDGE 3 

describes the following connections 



C004 



0,1 




The syntax of IMS C004 to edge lines is: 

c4.io.edge = C4 c4.fd, link o4Mnk.no [ , i/o] 
TO EDGE edge. id [,i/o] 



edge, id 



positive. integer 



The slots to edges section specifies which edges are connected to slots. It is not 
possible to separate the input and output channels for slot to edge connections. 
For example 

SLOT 1, LINK 3 TO EDGE 3 

describes the lollowing connection: 



SLOT1 



^EDGE3 



The syntax of a slot to edge connection is: 

sfot.to.edge = slot slotid, link fink.num TO edge edge.id 
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4,6 Error reporting 

4.6.1 Errors in the hardwire description 

There are a number of different types of error that may be detected by the MMS 

when reading Ihe hardwire file: 

• File Reading Errors 

• Syntax Errors 

• Range Checking Errors 

• Duplication Errors 

Most error messages should be self-explanatory. 

File reading errors 

If the MMS is not able to read the source files an error will be reported and 
explained. In some cases errors of this type will be detected first as a syntax 
eror and reported as such. 

Syntax errors 

Any syntax errors in the hardwire file will be reported, producing one of the 
following types of error message: 

'... unexpected symbol found ../ 
'... unexpected number found ...' 
'... unexpected word found ...' 

The symbol that was expected at that point is usually displayed as well, together 
with the source line number that the error was found on. This line is also dis- 
played in full beiow the enror message. 

For example, if the SIZES section of the hardwire file looked like this: 



SIZES 




T2 


2 


C4 


4 


SLOT 


32 


END 





The MMS wouEd produce the following error message: 

Error detected in HLl file at line 4 : 

- Unexpected symbol found ( ^END' ) . '^EDGE' was expected 

Line 4 : END 
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Range checking errors 

Numbers outside the following ranges will cause out of range error messages: 

• implementation limit restrictions 

• values defined in the SIZES section 

• link values outside range 0-3 

Duplication errors 

If any link from a slot, IMS C004 or edge is mentioned more than once in the 
HARDWIRE section, a duplication error will occur and an error message will be 
displayed. Similarly, duplicated IMS T212 links or IMS C004 IDs fn the T2CHAIN 
section wilJ give rise to errors. 

For example, 

C4 0, LINK 4, TO SLOT 4, LINK 3, I 
C4 0, LINK 4, O TO SLOT 7, LINK 0, I 



will produce an error message similar to: 

Error detected in HLl file at line x : 

- The C004 link in this connection is already involved 

in a C004 to slot connection 

Line x : C4 0, LINK 4, O TO SLOT 7, LINK 0, I 

Links may not be checked for duplication in the same order as they appear in 
the line. 



4.6.2 Errors in the softwfre description 

Many errors in the software definition are handled in the same way as the hardwire 
description. In addition to these errors, however, the MMS will also report soft 
connections which it is unable to establish. 
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This can be for one of two reasons: 

• A 'hard link' mentioned in a soft connection is not defined as connected 
anywhere in the hardwire description 

• Two hard channels are required to have a soft connection between them, 
but are connected to different IMS C004s making their connection impos- 
sible. 

To make it easier to report and correct such errors the MMS error messages 
break the process of establishing a soft link down into four stages. An error may 
be detected and reported at any of these stages: 

1 From 'from link' output to IMS C004 input 

2 From IMS C004 output to 1o link' input 

3 From 1o link' output to IMS C004 input 

4 From IMS C004 output to 'from link' input 




^ STAGE 3 _ 

fj^ 'i l EDGE OR 

^STAGE4 SLOT LINK 



For example, in the following line: 

SLOT 0, LINK 3 TO SLOT 1, LINK 

the stages are as follows: 

1 Check slot 0. link 3 output is connected to a IMS C004 input 

2 Check IMS 0004 output is connected to slot 1 , link input 

3 Check slot 1. link is connected to a IMS C004 input 

4 Check IMS C004 output is connected to slot 0, link 3 input 
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5.1 The system calls available 

The interface between the user program and the drivers is via a set of system 
calls. Because of the way a device driver integrates the device handling into 
the operating system, these system calls are the normal MS-DOS calls for doing 
input and output to a file or device. 

The device driver interfaces the BOOS to the operating system as a character 
device, this means that the device can be accessed by read or write calls 
with variable length buffers. 

• OPEN — Open device for reading or writing. 

• READ — Read a number of bytes trom the link. 

• WRITE — Write a number of bytes to the link. 

• lOCTL — locti calls to perform the tollowing: 

1 ReadFlags - Read the value of the transputer subsystem error 
flag and the driver timeout flag, as well as the status of the read 
and write channels of the link. 

2 SetFlags - Sets up the following actions: 

(a) Reset - Reset the transputer network. 

(b) Analyse - Analyse the transputer network. 

(c) Settimeout - Sets the tinfieout value and enables time- 
outs. 

• CLOSE — Close device. 

5.1.1 OPEN 

The open call to f^SDOS, generates a file descriptor to be used to access the 
device. The open call is passed a file name which MSDOS first checks against 
its list of character device names. If a match is found then the MSDOS sends 
all subsequent lO requests associated with the descriptor to the device driver 
rather than to a file. The IBM Disk Operating System Technical Reference gives 
a full description of how to call the operating system, the following code segment 
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shows a typical open call. 

name db 'LINKl', 

open_file: mov dx, offset name 
mo V al , MODE 
mov ah, 3Dh 
int 21h 

;File handle returned in AX 

orlrom C 

fd = open("LINKl", 0_RDWR) ; 

There is a problem however with the DOS open call to open a device. If there 
is no device which has the same name as the parameter then DOS will decide 
that the open call was to a real file, thus a file descriptor to an open file will be 
returned rather than to a device. In this way it is not possible by means of the 
open call to determine whether the device driver is installed or not 

There is however a DOS lOCTL call which returns information about the type of 
an open file descriptor. One of the bits in the returned status word corresponds 
to whether the descriptor points to a device or to a plain file. Tine procedure for 
opening a descriptor to the link should be to perform an open call on the name 
of the device, then perform an iocti call on the new descriptor to check that it 
does In tact reference the device rather than a file of the same name- 
Assuming the open file descriptor in bx, the following code will test whether the 
desriptor references a device: 

mov ax,4400h ; lOCTL call, function 

mov bx,<file handle> 

int 21h 

test dl,80h 

j z not_a_de vice 

The DOS lOCTL call is not usually implemented directly in C runtime libraries. 

5.1.2 READ 

Having opened the device, the read call allows data to be read from the link. The 
DOS Read call takes a file descriptor (which should be the descriptor obtained 
from open) a buffer pointer and a length. The buffer pointer and length are then 
passed to the device driver for service. 
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The device driver attempts to read the requisite number of bytes into the buffer, 
returning control to DOS and hence the user program when: 

« All the bytes have been read 

• A Timeout occurs see the timeout iocti call 

• The user presses ctrl-break 

If aEI the bytes were read» then read will return the passed length. If only part of 
the request was read due to either timeout or break detection then the number 
of bytes read is returned, if a timeout or break occured before any bytes were 
read then -1 is returned by the read call. 

5.1.3 WRITE 

The write call allows data to be written to the link adapter. The DOS Write call 
takes a file descriptor {which should be the descriptor obtained from open) a 
buffer pointer and a length. The buffer pointer and length are then passed to 
the device driver for service. 

In a similar way to the Read cafi, the device driver attempts to write the correct 
number of bytes from the buffer to the link, returning control to DOS and hence 
the user program when: 

• All the bytes have been written 

• A Timeout occurs see the timeout ioctI call 

• The user presses ctrl-break 

If all the bytes were written, then write will return the passed length. If only part of 
the request was written due to either timeout or break detection then the number 
of bytes written is returned. If a timeout or break occured before any bytes were 
written then -1 is returned by the write call. 

5.1.4 lOCTL 

In DOS, the ioctI call is a way of passing and retrieving control fnformation to 
the device or the device driver. This information is passed or retrieved using 
sub-function 02 and 03 of the IoctI (ah=44h) DOS INT 21 system call. The ioctI 
call is not usually supported directly by C compilers, it must be executed through 
either asssembly language or a generic operating system call interface of the 
language. 
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The call lo INT 21 h, AH^44li, AL=03h is used to write certain control information 
to the the device driver. In all cases a 32-bit (4-byte) vafue is passed into the 
call. The top 16-bits specify the kind of operation to be done, the bottom sixteen 
bits contain the parameter to the operation (if any) 



Top 16 bits 


Bottom 16 bits 


meaning 


OOOOh 


don't care 




Reset the root transputer 


0001 h 


don't care 




Assert analyse and reset 


0002h 


Timeout period (xO.1 
(0 means no timeout) 


seconds) 


Set the timeout period 



Example code to reset the root transputer: 



reset: word dw 00 



dw 00 






reset link; 






mov 


ah. 


44h 


mov 


al, 


03h 


mov 


bx, 


<fi 


mov 


ex, 


4 


mov 


dx. 


off 


push 


cs 




pop 


ds 





/Function 44 - 03 



<file handle> /Handle returned by open 

;Size of status string 
offset cs: reset word 



int 



21h 



/Address in dsrdx 
/Make DOS call 



The cal! to INT 21 h, AH=n44h, AL=02h is used to read the status information from 
the device driver, The call should be made, specifying a 32-bit transfer area in 
ex. On return the transfer area will be as follows: 



Bit Number 



Meaning 




1 
2 
3 



The transputer error llag Is set 

A Timeout occured on the last 10 operation 

The transputer link is able to accept at least one byte 

The transputer link has a least one byte available 
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Example code to retrieve the error flag: 

status dw 00 

dw 00 
rGset_link: 

mov ah,44h /Function 44 - 02 

mov al,02h 

mov bx, <file handle> 

mov ex, 4 ; Size of status string 

mov dx, offset cs : status_word 

push cs 

pop ds ; Addres s in ds : dx 

int 21h ;Make DOS call 

mov ax, [status] ;AX=returned status 

and al,l ;Only leave error bit 
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This chapter describes the host file server iserver, which loads programs 
onto transputers and transputer networks and provides the run-time environment 
through which programs communicate with the host. 



6.1 Introduction 

The host file server iserver provides two functions: 

« Loading programs and controlling transputer networks 

• Runtime access to host services tor application programs. 

At the application program level, all communications with the host file sen/er are 
through the libraries hostio . lib and streamio . lib. These are described 
in the 'Occam 2 toolset user manuat'. 

6.2 Running the server 

To run the host file server use the following command line: 

iserver {options} 
where: options is a list oi one or more options from table 6.1 . 

6-2.1 Supplying parameters to the program 

Any text on the command line that is not a server option is passed as parameters 
to the program. Valfd option strings will always be interpreted as server options 
and must not be used as program parameters. 

If iserver is invoked with no options, brief help information is displayed. 

6.2.2 Loading programs 

Before a program can be loaded onto a transputer network ft must be compiled, 
linked and made bootable using either the bootstrap tool iboot (for single 
transputer programs), or the configurer iconf {for multitranspuler programs). 
The file to be loaded will have a .btl or a .bx:v file extension. 
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Option 



Description 



SA 

SB filename 
sc filename 
SE 

SI 

SL name 
SP n 
SR 
SS 



Analyses the root transputer and peeks 8K of Its memory. 
Boots the program contained fn the named file. 
Copies the named file to the root transputer link. 
Terminates the server if the transputer error flag is set. 
Displays progress information as the program is loaded, 
Specifies link address or device name. 
Set size of memory to peek on Analyse to n KBytes. 
ResGts the root transputer and subsystem on the link. 
Serves the link, that is, provides host system support to pro- 
grams communicating on the host fink. 



Options must be preceded by '-' for UNIX based toolsets. 

Options must be preceded by '/' for non-UNIX based toolsets. 

Spaces between options and the case of letters in the parameters are not 

significant. 

Options may be in any order 

Option SB filename is equivalent to SR SS SI sc fUenBme. 



Table 6.1 Host file server options 

The name of the file containing the program to be loaded is specified using the 
'SB' option. If the file cannot be found an error is reported. This resets the board 
prior to loading the program. When the program has been loaded the server then 
provides host services to the program. 

Note: Using the 'SB' option is equivalent to using the SR, SS, SI and sc options 
together. 

To load a program onto a board without resetting the root transputer, use the 
'SC option. This should only be done if the transputer has already been reset, 
or has a resident program that can interpret the file. To reset the transputer 
subsystem use the 'SR' option. 

To terminate ti^e server immediately after loading the program use the 'SR' and 
'SC options together. This combination of options resets the transputer, loads 
the program onto the board, and terminates. 

To load a board in analyse mode, for example when you wish to use the debugger 
to examine the program's execution, use the 'SA' option to dump the first 8 Kbytes 
of the transputer's memory (starting from MOSTNEG INT). The data is stored 
in an internal buffer which is read by the idump tool when programs are to be 
debugged that use the root transputer. 
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6.2.3 Terminating the server 

To terminate the server press the host system break key. When the key \s, 
pressed the following prompt is displayed: 

(x> exit, Cs)hell, or (c) ontinue? 

To terminate the server type 'x' or press iRETURiMj . 

To suspend the server and resume the program later, type 's'. On DOS-based 
systems this option may require a host environment variable. On UDP-based 
versions this option should not be used — the target transputers may timeout 
and reset themselves. 

To abort the interupt and continue running the program, type 'c', 

6.2.4 Specifying a llnic address or name - option SL 

The server contains a default address or device name for communicating with 
boot from link boards. The address or name can be changed by specifying the 
*SL' option followed by the new value. Addresses can be given in decimal format, 
or in hexadecimal format by prefixing the number with '#'. 

The default address is overridden by the value of host environment variable 
TRANSPUTER, if this variable has been set. This variable is itself overridden by 
the address or name specified by the 'SL' option. 

6.2.5 Terminating on error - option se 

When debugging programs it is useful to force the server to terminate when the 
subsystem's error flag is set. To do this use the 'SE' option. This option should 
only be used for programs written entirely in OCCam and compiled in HALT 
system mode. If the program is not written entirely in OCCam then the error flag 
may be set even though no error has occurred. 
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6.3 Error messages 

A list of possible error messages which iserver may produce foltows. In many 
cases, the messages listed may be followed by an extra message which gives 
additional information. This information is host specific. 

Aborted by user 

The user internjpted the server, by pressing [ctri] [C] or fCtrOlBriikl . 
Bad link spedflcation 

The link name specified is not valid. 

Boot filename is too long, maximum size is /rumi^gr characters 

The specified filename was too long, number is the maximum size for 
filenames. 

Cannot find boot file fiiename 

The server cannot open the specified file. 

Command line too long (at string) 

The maximum permissible command line length has been exceeded. The 
overflow occurred at string. 

Copy filename Is too long, maximum size Is number characters 

The specified fiiename was too long, number is the maximum size for 

filenames. 

Error flag raised by transputer 

The program has set the error flag. Debug the program. 
Expected a filename after -SB option 

The 'SB' option requires the name of a file to load. 
Expected a filename after -SC option 

The 'SC option requires the name of a file to load. 
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Expected a name after -SL option 

The 'SL' option requires a link name or address. 
Expected a number after -SP option 

The 'SP' option must specily the number of Kbytes to peek. 

Failed to aliocate CoreDump buffer 

The 'SP' option was used and the server was unable to allocate enough 
memory to allow the transputer's memory to be copied. 

Failed to anaiyse root transputer 

The link driver could not analyse the transputer 
Failed to reset root transputer 

The link driver could not reset the transputer. 
Link name is too long, maximum size is number characters 

The specified name was too long, number Is the maximum length. 

Protocol error, message 

Incorrect protocol on the link. This can happen if there is a hardware 
fault, or if an incorrect version of the SBtv&r is used. 

message can be any of the following: 

got number bytes at start of a transaction 

packet size is too targe 

read nonsense from the link 

timed out getting a further dataname 

timed out sending repiy message 

For more information about server protocols see chapter 7. 
Reset and anaiyse are incompatibie 

Reset and analyse options cannot be used together. 



72 OEK 227 01 January 1990 



44 6 JNMOS server 

Timed out peeking word number 

The server was unable to analyse the transputer. 
Transputer error fJag has been set 

The progrart) has set the error flag. Debug the program. 

Unable to access a transputer 

The server was unable to gain access to a link. This occurs when the 
link address or device name, specified either with the SL option or the 
TRANSPUTER environment variable, is incorrect. 

Unable to free transputer Hnk 

The server was unable to tree the link resource because of a host error. 
The reason tor the error will be host dependent. 

Unable to get request from link 

The server failed to get a packet from the transputer because of some 
general failure. 

Unable to write byte number to the boot link 

The transputer did not accept the file for loading. This can occur if the 
transputer was not reset or because the file was corrupted or in incorrect 
format. 
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definitions 



This section provides a technical description of the server's functionality and 
the protocol used lo impfement requests to and replies from the server. This 
information is intended to help those porting the server to a new host machine, 
or are extending server functionality. 



7,1 iserver protocol 

Every communication, both to and from the server, is a counted array of bytes. 
The first two bytes are a (little endian) count of the following message length. 
In the lo-server direction, there is a minimum packet length of 8 bytes (i.e. a 
minimum message length of 6 bytes). In both to and from directions there is a 
maximum packet length of 1024 bytes. A further restriction is that the message 
must always be an even number of bytes. 



s1 s2 message of length s1+(256*s2) 



In Occam these messages can be routed as IMT16: ; [Ibyte protocol. 

The server code on the host can lake advantage of the facl that it will always be 
able to read 8 bytes from the link at the start of a transaction. 



7.2 Server functionality 

This section describes the basic set of server functions. All versions of the 
iserver will support these functions, enabling programs to be ported between 
different versions of the toolset. 

The functions implemented by the server are separated into three groups: 

1 Interacting with files 

2 Interacting with the host environment 

3 interacting with the server Itself 

In the descriptions that foliow, the arguments and results of server calls are listed 
in the order that they appear in the data part of the protocol packet. The length 
of a packet is the length of al! the items concatenated together, rounded up to 
an even number of bytes. 
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Ail server cails return a result byte as the first item in the return packet. If the 
operation succeeds the result byte will be zero, If the operation fails the result 
byte will be non-zero. The result will be one (1) in the special case where the 
operation failed because it was not implemented^ If She result is not zero, some 
or all of the return values may not be present, resulting in a smafler return packet 
than if the calf was successful. 

In the descriptions below, Occam types are used to define the format of data 
items in the packet. Ali integer types are communicated least significant byte 
first. Negative integers are represented in 2s complement. Strings and other 
variable length blocks are introduced by a 16 bit signed count. 

7.2.1 File connmands 

Open files are identified with 32 bit descriptors. There are three predefined open 
files: 

standard, input 

1 standard output 

2 standard error 

If one of these is closed it may not be reopened. 



1 Result values between 2 and 127 are defined to have particular meanings by OCCam 
server libraries, Result values of 128 or above are specific to the implementalion of a server. 
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Fopen - Open a file 

Synopsis; Streamid = Fop6it( Name, Type, Mode ) 

To server: BYTE Tag =10 

INTl 6 : ; [ ] BYTE Name 

BYTE Type = 1 or 2 

BYTE Mode = 1, . .6 

From server: BYTE Result 

INT32 Streamid 

Fopen opens the file Name and, if successful, returns a stream identifier 
Streamid. 

Type can take one of two possible values: 

1 Binary. The file will contain raw binary bytes 

2 Text. The file will be stored as text records. Text files are host- 
specified. 

Mode can have 6 possible values: 

1 Open an existing file for input 

2 Create a new file, or truncate an existing one, for output 

3 Create a new file, or append to an existing one, for output 

4 Open an existing file for update (both reading and writing), starting 
at the beginning of the file 

5 Create a new file, or truncate an existing one, for update 

6 Create a new file, of append to an existing one, for update 

When a file is opened for update (one of the last three modes above) then 
the resulting stream may be used for input or output. There are restric- 
tions, however. An output operation may not follow an input operation 
without an intervening Fseek, Ftell or Ff lush operation. 

The number of streams that may be open at one time is host-specified, 
but will not be less than eight (including the three predefines). 
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- Close a file 






Synopsis: 


Fclose( 


Streamid ) 


To server: 


BYTE 


Tag = 11 




INT32 


Streamid 


From server: 


BYTE 


Result 



Fdose closes a stream streamid which should be open for input or out- 
put. FctosG flushes any unwritten data and discards any unread buffered 
input before closing the stream. 



Fread - Read a block of data 

Synopsis: Data = Fread ( Streamid, Count ) 

To server : 



BYTE 


Tag =12 


INT32 


Streamid 


INT16 


Count 



From server: BYTE Result 

INT16: : []BYTE Data 

This function is obsolete. See the definition of FGetBlock tor its 

replacement. 

Fread reads Count bytes of binary data from the specified stream. Input 
stops when the specified number of bytes are read, or ihe end of file Is 
reached, or an error occurs. If Count is less than one then no input is 
done. The stream is left positioned immediately after the data read. If 
an error occurs the stream position is undefined. 

Result is always zero. The actual number of bytes returned may be 
less than requested and Feof and Ferror should be used to check for 
status. 
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Fwrlte - Write a biock of data 

Synopsis: Written — Fwrite< Streamid, Data } 

To server: BYTE Tag = 13 

INT32 Streamld 

XNT16; : I] BYTE Data 

From server: BYTE Result 

INT16 Written 

This function is obsolete. See the definition of FPutBiock for its 
replacement. 

Fwrite writes a given number of bytes of binary data to the specified 
stream, which should be open lor output. \1 the length of Data is less 
than zero then no output is done. The position of the stream is advanced 
by the number of bytes actually written. If an error occurs then the re- 
sulting position if undefined. 

Fwrite returns the number of bytes actually output in Written. Result 
is always zero. The actual number of bytes returned may be less than 
requested and Feof and Ferror should be used to check for status. 

If the Streamld is 1 (standard output) then the write is automatically 
flushed. 
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Fgets - Read a JIne 

Synopsis: Data = Fgets ( Streamid, Count ) 

To server; BYTE Tag = 14 

INT32 Streamid 

INT16 Count 

From server: BYTE Result 

INT16: : [JBYTE Data 



Fgets reads a line from a stream whicti must be open for input. Charac- 
ters are read until end of file is reached, a newline character is seen or 
the number of characters read is not less than Count. 

If the input is terminated because a newline is seen then the newline 
sequence is not included in the returned array. 

If end of file is encountered and nothing has been read from the stream 
then Fgets fails. 



Fputs - Write a line 

Synopsis : Fputs ( Streamid, String ) 

To server: BYTE Tag = 15 

INT32 Streamid 

INT16: : []BYTE String 

From server: BYTE Result 



Fputs writes a line of text to a stream which must be open for output. 
The host-specified convention for newline will be appended to the line 
and output to the file. The maximum line length is host-specified. 
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Fflush - Flush a stream 

Synopsis; Ff lush ( Streamid ) 

To server: BYTE Tag =16 

INT32 Streamid 

From server: BYTE Result 



Fflush flushes the specified stream, which should be open for output. Any 
internally buffered data is written to the destination device. The stream 
remains open. 



Fseek - Set position in a file 

Synopsis: Fseek ( Streamid, Offset, Origin ) 



To server: 


BYTE 


Tag = 17 




INT32 


Streamid 




INT32 


Offset 




INT32 


Origin 


From server: 


BYTE 


Result 



Fseek sets the file position for the specified stream. A subsequent read 
or write will access data at the new position. 

For a binary file the new position will be Offset characters from 
Origin which may take one of three values: 

1 Set. the beginning of the file 

2 Current, the current position in the file 

3 End, the end of the file 

For a text stream, Offset must be zero or a value returned by Ftell. If the 
latter is used then Origin mus! be set to 1 . 
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Ftell - Find out position in a file 

Synopsis: Position = Ftell ( Streamld ) 

To server: BYTE Tag = 18 

INT32 Streamld 

From server: BYTE Result 

INT32 Position 

Ftell returns tiie current file position lor streamld. 

Feof - Test for end of file 

Synopsis: Feof( Streamld ) 

To server: BYTE Tag =19 

INT32 Streamld 

From server: BYTE Result 

Feof succeeds if the end of file indicator for streamld is set 

Ferror - Get file error status 

Synopsis: ErrorNo, Message = Ferror (Streamld) 

To server: BYTE Tag = 20 

INT32 Streamld 

From server: BYTE Result 

INT32 ErrorNo 

IHT16: : []BYTE Message 

Ferror succeeds if the error indicator for streamld is set. If it is, Fer- 
ror returns a host-defined error number and a (possibly null) message 
corresponding to the last file error on the specified stream. 
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Remove - Delete a file 

Synopsis: Remove ( Name ) 

To server: BYTE Tag =21 

INT16: : []BYTE Name 

From server: BYTE Result 

Remove deletes the named file. 
Rename - Rename a file 

Synopsis: Rename ( OldName, NewName ) 

To server: BYTE Tag = 22 

INT16: : []BYTE OldName 
INT16 : ; [ ] BYTE NewName 

From server: BYTE Result 

Rename changes the name of an existing file OldName to NewName. 
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FGetBlock - Read a block of data and return status 

Synopsis: Data, Result = FGetBlock (Streamld^ Count) 

To server: BYTE Tag = 23 

INT32 Stxeamid 

INT16 Count 

From server: BYTE Result 

INT16: : [IBYTE Data 



FGetBlock reads Count bytes of binary data from the specified stream. 
Input stops when the specified number of bytes are read, or the end of 
file is reached, or an error occurs. If Count fs less than one then no 
Input is done. The stream is left positioned immediately after the data 
read. If an error occurs the stream position is undefined. 

The actual number of bytes returned may be less than requested. In the 
case of Result indicating a failure Feof and Ferror should be used to 
determine the cause of the error. 

This function is preferred over the Fread function, which should no longer 
be used. 
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FPutBlock - Write a block of data and return status 

Synopsis: Written, Result = FPutBlock (Straamid, Data) 

To server: BYTE Tag = 24 

INT32 Streamld 

IST16: : []BYTE Data 

From server: BYTE Result 

INT16 Written 



FPutBlock writes a given number of bytes of binary data to the specf- 
fied stream, wiiich should be open for output. If the length of Data is 
less than one then no output is done. The position of the stream is ad- 
vanced by the number of bytes actually written. If an error occurs then 
the resulting position rf undefined. 

FPutBlock returns the number of bytes actually output in Written, The 
actual number of bytes returned may be less than requested and Feof 
and Ferror should be used to check for status. 

If the Streamld is 1 (standard output) then the write is automatically 
flushed. 

This function is preferred overthe Fwrite function, which should no longer 
be used. 



7.2.2 Host commands 

Getkey - Get a keystroke 

Synopsis: Key = GetKeyO 

To server: BYTE Tag =30 

From server: BYTE Result 

BYTE Key 



GetKey gets a single character from the keyboard. The keystroke is 
waited on indefinitely and will not be echoed. The effect on any buffered 
data in the standard input stream is host-defined. 
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Pollkey - Test for a key 

Synopsis: Key = PollKey () 

To server: BYTE Tag =31 

From server: BYTE Result 

BYTE Key 

PollKey gets a single character from the keyboard, If a keystroke is not 
available then PollKey returns immediately with a non-zero result. If a 
keystroke is available it will not be echoed.The effect on any buffered 
data in the standard input stream is host-defined. 

Getenv - Get environment variable 

Synopsis: Value = Getenv ( Name ) 

To server: BYTE Tag = 32 

INT1€: : []BYTE Name 

From server: BYTE Result 

INT16: : []BYTE Value 

Getenv returns a host-defined environment string for Name. If Name is 
undefined then Result will be non-zero. 

Time - Get the time of day 

Synopsis: LocalTime, OTCTime = Time{) 

To server: BYTE Tag = 33 

From server: BYTE Result 

INT32 LocalTime 

INT32 UTCTime 



Time returns the local time and Coordinated Universal Time if it is avail- 
able. Both times are expressed as the number of seconds that have 
elapsed since midnight on 1st January, 1970. If UTC time is unavailable 
then it will have a value of zero. 
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System - Run a command 

Synopsis: Status = System ( Command ) 

To server: BYTE Tag = 34 

INT 16 : : [ ] BYTE Command 

From server: BYTE Resul-t 

INT32 Status 

System passes the string Command to the host command processor for 
execution. If Command is zero length then System will succeed if there 
is a command processor, if Command is not null then status is the 
return value of the command, which is host-defined. 

7.2.3 Server commands 

Exit - Terminate the server 

Synopsis: Exit ( Status ) 

To server: BYTE Tag = 35 

INT32 Status 

From server: BYTE Result 

Exit terminates the server, which exits returning status to its caller. 

if Status has the special value 999999999 then the server will terminate 
with a host-specific 'success' result. 

if Status has the special value -999999999 then the server will terminate 
with a host-specific 'failure' result. 



72 OEK 227 01 January 1990 



58 7 Server protocol definitions 

CommandLlne - Retrieve the server command line 

Synopsis: String = CommandLine ( All ) 

To server; BYTE Tag = 40 

BYTE All 

From server: BYTE Result 

INT16 : : [ ] BYTE String 



CommandLine returns the command line passed to the server on invo- 
cation. 

If All is zero the returned string is the command line, with arguments 
that the sen/er recognised at startup removed. 

If All IS non-zero then the string returned is the entire command vector 
as passed to the server on startup, including the name of the server 
command itself. 

Core - Read peeiced memory 

Data = Core( Offset, Length ) 

Tag =41 

Offset 

Length 

Result 
INT16: : []BYTE Core 

Core returns the contents of the root transputer's memory, as peeked 
from the transputer when the server was invoked with the analyse option. 

Core (ails if Offset is larger than the amount of memory peeked from the 
transputer or if the transputer was not analysed. 

ff (Offset + Length) is larger than the total amount of memory that was 
peeked then as many bytes as are available from the given offset are 
returned. 



Synopsis 


Data : 


To server: 


BYTE 




INT32 




INT 16 


From server; 


BYTE 
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Version - Find out about the server 

Synopsis: Id = Version () 

To server: byte Tag = 42 



From server: 


BYTE 


Result 




BYTE 


Version 




BYTE 


Host 




BYTE 


OS 




BYTE 


Board 



Version raturns four bytes containing identification infornnalion about the 
server and the host it is running on. 

If any of line bytes has the value then that information is not available. 

Version identifies the server version. The byte value should be divided 
by ten to yield a version number. 

Host identifies the host box. Currently 8 are defined: 

1 PC 5 IBM 370 Architecture 

2 NEC-PC 6 Sun-4 

3 VAX 7 Sun-386i 

4 Sun-3 8 Apollo 

OS identifies the host environment. Currently 5 are defined: 

1 DOS , ^ -,_ 
« ., ■• ^ SunOS 

3 VMS ^ ^""^ 

Board identifies the interface board. Currently 1 1 are defined: 

' ^°°^ 7 QTO 

2 ^°^° 9 CAT 

5 B014 ,, ,,„n I- I 

6 DRX-11 

INMOS reserves numbers up to and including 127 for these three fields. 
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A Rebuilding the server 



The INMOS server consists of a set of C modules and header files. The source 
can be altered to be used with various applications. When this is done the 
server needs to be recompiled and linked using the hosts C connpiler, to make 
Ihis process easier a Makefile is supplied. 
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B INMOS Standard link 
access routines 



This appendix describes a standard set of 'C bindings for talking to transputer 
links from a liost computer. These routines are independent of the host spe- 
cific software that drives the hardware (e.g. a device driver, or an assembly 
language routine). INMOS has implemented versions of these routines for all its 
development boards across severai hosts and uses this scheme in its server. 

If you wish to create a version of the server for your own board it should only be 
necessary to replace these functions in the server provided. 



B.1 Link initialisation 

/* OpenLink 

* 

* Ready the link associated with ^Hame' . 

* If ^Name' is null or '"" then 

* any free link can be used. 

* Returns any positive integer as a link id or 

* a negative value if the open fails. 
*/ 

int ppenLink { Name ) 
char *Naine; 

i 
y 

/* CloseLink 
* 

* Close the active link ^Linkld' . 

* Returns 1 on success or 

* negative if the close failed. 



int CloseLink (Linkid ) 

int Linkid; 
{ 
} 
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B.2 Data operations 

/* ReadLinlc 

* 

* Read ^Count' chars into ^Buffer' 

* from th« specified link, 

* Linkld is a valid link identifiar, 

* opened with OpenLink. 

* ^Timeout' is a non negative integer representing 

* tenths of a second. 

* A ^Timeout' of zero is an infinite timeout. 

* The timeout is for the complete operation. 

* If ^Timeout' is positive then ReadLink may return 

* having read less than the number of chars asked for. 

* Returns the number of chars placed in ^Buffer' 

* (which may be zero) or negative to indicate an error. 
*/ 

int Readliink ( Linkid, Buffer, Count, Timeout ) 
int Linkid; 

char *Buff6r; 

unsigned int Count; 

int Timeout; 
{ 
) 

/* WriteLink 

* 

* Write 'Count' chars from ^Buffer' 

* to the specified link. 

* Linkid is a valid link identifier, 

* opened with OpenLink. 

* ^Timeout' is a non negative integer representing 

* tenths of a second. 

* A ^Timeout' of zero is an infinite timeout. 

* The timeout is for the complete operation. 

* If ^Timeout' is positive then WriteLink may return 

* having written less than the number of chars asked for. 

* Returns the number of chars actually written 

* (which may be zero) or negative to indicate an error. 
*/ 

int WriteLink ( Linkid, Buffer, Count, Timeout ) 
int Linkid; 

char *Buffer; 

unsigned int Count; 

int Timeout; 
{ 
} 
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B.3 Subsystem control 

/* ResetLink 

* 

* Reset the subsystem associated 

* with the specified link. 

* Returns 1 if the reset is successful^ 

* negative otherwise. 
*/ 

int ResetLink ( Linkid ) 

int Linkid; 
{ 
> 

/* AnalyseLink 

it 

* Analyse the subsystem associated 

* with the specified link. 

* Returns 1 if the analyse i5 successful, 

* negative otherwise. 
*/ 

int Analyseliink ( Linkid ) 

int Linkld; 
{ 
} 



B.4 Error testing 

/* TestError 

* 

* Test the error status associated 

* with the specified link. 

* Returns 1 if error is set, if it is not and 

* negative to indicate an error. 
*/ 

int TestError ( Linkid ) 

int Linkld; 
{ 
> 
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B.5 Data ready tests 

/* Test-Read 

* Test input status of the link. 

* Returns 1 if ReadLink will return one byte 

* without timeout, 

* if it may not and negative to indicate an error. 
*/ 

int TestRead { LinkXd ) 

int Linkid; 
{ 
) 

/* TestWrite 

* 

* Test output status of the link. 

* Returns 1 if WriteLinfc can write one byte 

* without timeout, 

* if it may not and negative to indicate an error. 



int TestWrite ( Linkid ) 

int Linkid; 
{ 
} 
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C Softwire description 
language 



sofiwire.de$cription= softwire 

{ board. so ftwi res} 
END 

boardsoftwires =PIPE board.id 
{ softwireJine} 

softwireJine = slotto.shtUne 

I slotto.edge.line 
I edge.to.edge.line 

slottcstotMne =SJjO'T slot.id, link Unk.num TO SLOT sfotid, 
LINK link.num [via.section] 

via.section =via edge edge .id, edgeJd 

slotto.edgeJine = slot sfot.id, link linkMum to edge edgeJd 

edge.to.edge.line = EDGE edge.id TO edge il edges.id 

linkMum = 

11 
12 

13 

sloUd = positive. Integer 

edge.id = positive.integer 
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D Hardwire description 
language 



hardwire, description 



{i board, definition } 
pipeline, description 



positive. integer = a positive integer varying between implementations 

pipeline.description = pipe { board.name } 



board.definition 


= DEF board.name 




sizes 




tZchain 




hardwires 


sizes 


= SIZES 




T2 positive, integer 




C4 positive, integer 




SLOT positive.integer 




EDGE positive.integer 




END 


t2. chain 


= T2 CHAIN 




{ t2.c4Jlne} 




END 


t2.c4Jine 


= T2 t2.id. LINK chainJink.num C4 c4.id 


tZid 


= positive.integer 


chain. link. num 


^ 




1 3 


link.num 


= 
1 1 

1 2 






1 3 



c4.id 



0..31 
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hardwires = HARDWIRE 

{ hardwire. line } 

END 

hardwire, line = slot. to. slot 
I c4.to.slot 





1 c4.to.edge 




\ slot.to.edge 


slot.id 


^ posttive.integer 


c4.link.no 


= positive.inieger 


edge. id 


= positive.integer 



slot.to.slot = SLOT slot.id, LINK tink.num TO SLOT slot.id, 
LINK {ink.num 

c4.to.siot = C4 c4.id, LINK c4.link.no I i/o] TO SLOT slot.no, 

LINK tinkMuml i/o] 

i/o = I 

i O 

c4Ao.edge = C4 c4.id, LINK c4Jink.no [ , i/o] TO EDGE edge.id [, i/o] 

sloLto.edge = SLOT slot.id, link link.num TO edge edge.id 
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E Edge mappings for the 
BOOS 



The MMS2 hardwire file for the BOOS as supplied in the file 'b008' contains EDGE 
definitions for the output connectors of the BOOS. The edge definitions map onto 
the connectors as follows (The connector label on the link break-out board is 
also given) 



Hardwire Mnemonic 


Signal Name 


Breakout Label 


EDGED 


EdgeLinkO 


LO 


EDGE1 


EdgeLinkI 


L1 


EDGE 2 


EdgeUnk2 


L2 


EDGE 3 


EdgeLinkS 


L3 


EDGE 4 


EdgeLink4 


L4 


EDGES 


Edge Links 


L5 


EDGES 


Edge Links 


L6 


EDGE 7 


Edge Link? 


L7 


EDGES 


PatchLinkO 

(via patch header) 


L8 


EDGE 9 


PatchLinkO 

(via patch header) 


L9 
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F The IMS C004 
programmable link 
switch 



The MS C004 programmable link switch provides a full crossbar switch be- 
tween 32 link inputs and 32 link outputs. It will switch links running at standard 
transputer speeds (10 and 20 Mbits/sec). The IMS C004 is programmed via a 
separate serial link called the configuration link. 

Each input and output is identified by a number in the range to 31. A con- 
figuration message consisting of one, two or three bytes is transmitted on the 
configuration Jink. The configuration messages sent to the switch are shown 
below. 



Configuration Message 


Function 


[O][input][output] 
[1] [linkl] [IInk2] 

[2] [output] 

[3] 

[4] 

[5] [output] 

[6][link1][link2] 


Connects Input to output 

Connects Ilnk1 to Iink2 by connecting the input 
of Hnitl to the output of Iink2 and the input of 
linl<2 to the output of Ilnk1. 

Enquifes which input the output is connectecf to. 
The IMS C004 responds with the input. The most 
significant bit of this byte indicates whether the 
output is connected (bit set high) or disconnected 
(bit set low). Early versions do not respond to the 
command. 

This command byte must be sent at the end of ev- 
ery configuration sequence which sets up a con- 
nection. The IMS C004 is then ready to accept 
data on the connected inputs- 
Resets the switch. All outputs are disconnected 
and held low. This also happens when Reset is 
applied to the IMS C004. 

Output output is disconnected and held low. 

Disconnects the output of linkl and the output of 
Iink2 



For more detailed information on the IMS C004 see [3] and [5]. 
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G The stages of IMS 
C004 configuration 



This appendix is designed to give some extra information about the method 
used to configure the system of motherboards. The configuration tal<es place in 
a number of stages, as described beJow. 

A special IMS T212 worm is sent down the configuration pipeline which looks for 
IMS T212s attached to link 2. The total number of IMS T212s found is passed 
back up the pipeline to the host transputer. If the number found is different 
from the number described in the hardwire file then an error is reported and the 
configuration abandoned. 

At this stage a hardware reset of the IMS C004s is performed (if available on 
the motherboard in use), by writing to the externai memory interface of the IMS 
T212. 

The host transputer now sends the Identification numbers of the IMS C004s In 
the system down the pipeline. This enables the worm on any particular IMS 
T212 to intercept commands intended for the IMS C004s it controls and pass on 
commands for others. 

The configuration pipeline is now in a state where it is able send configuration 
data to the IMS C004s. 

Before sending any configuration data to the pipeline, the host transputer sends 
a software reset command to each IMS C004 in the system to ensure that the 
IMS C004S are in a known state. 

The configuration data for the network is then send down the configuration 
pipeline, each command preceded by the identification number of the IMS C004 
It is meant for. 

The configuration will now be complete and it is possible to reset the system of 
motherboards without destroying the soft configuration. 
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H Distribution disk 



H.1 Contents of the release disk 

The S708 is supplied on standard 5^" 360K and 3^" 720K MS-DOS floppy disks. 

Tlie disks contain the following files; 

bOOS 

ibmpc . itm 
iserver.exe 
inms2 .b4 
softwire 
s70adriv. sys 

The directory 'iserver' on the release disk, contains the following files: 

b004asni.asm 
b0041ink.c 
bOOSlink.c 
bOlllink.c 
b0141ink.c 
change.log 
filecc 
he lies .c 
hostc.c 
inmos .h 
iserver . c 
iserver .h 
link.c 
inakef lie 
msdosc.c 
pack.h 
qtOlink.c 
serverc . c 
s386ilink. c 
vmserr .msg 
updlink . c 
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J Glossary 



Analyse Assert a signal to a transputer to tell it to halt at the ne>ct de-scheduling 
point, and allow the state of the processor to be read. In the contejct of 
'analysing a network', analyse all processors in the network. One of the 
system control functions on transputer boards. 

Bootstrap A transputer program, loaded from ROM or over a link after the trans- 
puter has been reset or analysed, which initialises the processor and 
loads a program for execution (which may be another loader). 

Hard channels Channels which are mapped onto links between processors in 
a transputer network (used in contrast to Soft channels). 

Module Motherboard Motherboards are provided to interface to various buses. 
They have slots for inserting INMOS TRAMs and switch chips which can 
be programmed to connect the transputers in different topologies. 

Network A set of transputers connected together using links, as a connected 
graph (i.e. in such a way that there is a path, via links, and other trans- 
puters, from one transputer to every other transputer in the set). 

Reset Transputer system initialisation control signal. 

Root transputer The transputer connected directly to the host machine. 

Server A program njnning in a host computer attached to a transputer network 
which provides access to the filing system and terminal I/O of the host 
computer. The server is normally used to boot up the network as well. 

Soft channels Channels declared and used within a process running on a single 

transputer (used in contrast to Hard channels). 

TRAM Standard hardware module which can be used to quickly construct sys- 
tems for a particular application or for a prototype. TRAMs consist of 
transputers, memory and sometimes application specific circuitry. They 
conform to a published specification. 

Worm A program that will distribute itself through a network of transputers (per- 
haps with an unknown topology) and allow all the processors in the net- 
work to be loaded, tested or analysed. 
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